|
|
PocketCNetLib API 1.0.0
© 2003 Serg Koren & VisualNewt Sofware.
All rights reserved.The following NetLib API calls are supported internally by the library:
- NetLibReceive
- NetLibGetHostByName
- NetLibSend
- NetLibSocketConnect
- NetLibSocketClose
- NetLibSocketOpen
- NetLibClose
- NetLibOpen
- SetAppNetTimeout
- GetNetLibNumber
(others will be added as requested by registered users.)
The PocketCNetLib API calls (exposed to PocketC) include:
- nlVersion
- nlCheckInstalled
- nlGetNetLibNumber
- nlErrorString
- nlNetLibOpen
- nlNetLibGetHostByName
- nlNetLibSocketConnect
- nlNetLibSocketOpen
- nlNetLibSend
- nlNetLibReceive
- nlNetLibSocketClose
- nlNetLibClose
- nlSetAppNetTimeout
See the example test program for a complete example of the API's use.
pointer nlVersion();
parameters:
<none>
Returns the version number of the PocketCNetLib. The return is a pointer to a string.
pointer p;p = nlVersion();alert(*p);
int nlCheckInstalled();
parameters:
<none>
Returns 5000 if NetLib is installed on the device, otherwise returns an error code which can be passed to nlErrorString.
int nlGetNetLibNumber();
parameters:
<none>
Returns the NetLib reference number, otherwise returns an error code which can be passed to nlErrorString.
Note: the reference number will be less than 5000, while an erro code will be greather than 5000.
pointer nlErrorString(int errorCode);
parameters:
integer error code obtained from PocketCNetLib
Accepts an error code as returned by PocketCNetLib, and returns a pointer to the corresponding error string. NOTE: Do not pass non PocketCNetLib errors into this routine. PocketCNetLib error codes start at 5000. To get the corresponding PalmOS NetLib errror code merely subtract 5000 from the PocketCNetLib error code. That is:
PalmOS NetLib error code = PocketCNetLib error code - 5000;
pointer p;p = nlErrorString(5122);alert(*p);
int nlNetLibOpen(int refNum);
parameters:
integer NetLib reference number
Opens the NetLib given its reference number (obtained via nlGetNetLibNumber). Returns 5000 if successful, otherwise returns an error code that can be passed to nlErrorString.
pointer nlNetLibGetHostByName(int refNum,string hostName,int timeout);
parameters:
integer NetLib reference number
string host name to be translated
integer timeout in seconds
Translates a host name to a TCP/IP dotted-IP address of the form xxx.xxx.xxx.xxx. Returns a pointer to a string that eitherrepresents the dotted IP address or a 5000-based error code that can be passed to nlErrorString after conversion to an integer.
string host; pointer p;host = "www.palmsource.com"; p = nlNetLibGetHostByName(refnum,host,5); puts(host + " - " + *p + "\n"); // length of 4 indicates an error code if (strlen(*p) == 4) {//handle errors here}
int nlNetLibSocketConnect(int refNum,int socketNum,string host,string port,int timeout);
parameters:
integer NetLib reference number
integer socket reference number obtained from nlNetLibSocketOpen
string host name OR dotted IP address
string timeout in seconds
Attempts to connect to the specified host-port combination given the NetLib and socket reference numbers. This call will accept either a dotted IP address in the form of "255.255.255.255" or a host name "www.mysite.com", and will do an internal name to IP address lookup if necessary. Returns 5000 if the connection succeeds, otherwise it returns an error code that can be passed to nlErrorString.
NOTE: The demo version of PocketCNetLib will return an error code 5003 if the host or IP address maps to something other than www.visualnewt.com. That is, the demo will only connect to www.visualnewt.com.
int nlNetLibSocketOpen(int refNum,int domain, int type, int timeout);
parameters:
integer NetLib reference number
integer domain 0, or 2 (see PalmOS NetSocketAddrEnum documentation). You will usually use 2.
integer type 1,2,3,4 (see PalmOS NetSocketTypeEnum documentation). You will usually use 1.
integer timeout in seconds
Obtains a socket and attempts to open it. If successful, nlNetLibSocketOpen returns a socket reference number,otherwise a 5000-based error code that can be passed to nlErrorString.
nlNetLibSend(int refNum, int socketNum, string buffer, string dottedIP, string port, int timeout);
parameters:
integer NetLib reference number
integer socket reference number
string buffer to transmit (NOTE: This buffer is limited to 2048 bytes within PocketCNetLib.)
string dotted IP address of the host to send to or "" if you wish to send to the currently open socket. (NOTE: This call does not resolve host names.)
string port to send to or "" if you wish to send to the currently open socket.
integer timeout in seconds
Attempts to send a string buffer of data to the previously opened socket, or to the specified dotted IP address and port combination. Set the dotted IP and port numbers to "" to specify the previously opened socket. Returns the total number of bytes sent or a 5000 based error code that can be passed to nlErrorString.
pointer nlNetLibReceive(int netRef, int socketNum, int flags, int timeout);
parameters:
integer NetLib reference number
integer socket reference number
integer flags 0. (See PalmOS I/O Flags Documentation).
integer timeout in seconds
Reads data from the previously opened socket and returns a pointer to the data. Returns a pointer to a 5000 based string error code. This must be converted to an integer to be passed to nlErrorString.
int err;pointer p;p = nlNetLibReceive(refnum,socketrefnum,0,5); // length of 4 indicates an error code if (strlen(*p) == 4) { // convert error in string form to integer err = *p; p = nlErrorString(err); alert(*p); } puts("RECEIVED : " + *p + "\n");
int nlNetLibSocketClose(int refNum, int socketNum, int timeout);
parameters:
integer NetLib reference number
integer socket reference number
integer timeout in seconds
Attempts to close the socket number specified. Returns 5000 if successful, or an error code that can be passed to nlErrorString.
int nlNetLibClose(int refNum, int closeMode);
parameters:
integer NetLib reference number
integer 0 = use timed close, 1 = close immediately (see PalmOS NetLib documentation).
Closes the NetLib. Returns 5000 if successful, or a 5000 based error code that can be passed to nlErrorString.
int nlSetAppNetTimeout(int timeout);
parameters:
integer timeout in seconds
Sets the AppNetTimeout variable that determines the application's timeout on network activity. See PalmOS NetLib documentation for more information. This call always returns 5000 (success).
Support:
PocketCNetLib support is a development tool. As such, only the tool is supported, not any code you attempt to develop using the tool. It is up to you to determine whether the problem is in your code or the library's. Support will be provided to registered users only, and priority will be given to registered users for enhancement requests.
Bugs and enhancement requests should be sent to: Serg@VisualNewt.com
